home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / Online / Epic4 / share / epic / help / 7_docs / Arrays < prev    next >
Encoding:
Text File  |  2001-03-21  |  3.1 KB  |  66 lines
  1. Karll's Array Suite                                                         
  2.  
  3. EPIC supports a large number of different data types.  Among the least used,
  4. and least understood, are Karll's arrays.  This is mostly due to the lack of
  5. publicized documentation for them.  No more.
  6.  
  7. IrcII has long supported an array type.  These are best identified as hash
  8. arrays (or associative arrays, for Perl hackers).  However, Karll's arrays
  9. are different, more in line with the traditional notion of an array.  Due to
  10. how EPIC stores information, these arrays are not like normal variables or
  11. hashes, and require special function to access and manipulate them.
  12.  
  13. Arrays are indexed sequentially, starting with 0 (zero).  An array is
  14. created when item 0 in a previously nonexistent array is defined:
  15.  
  16.    $setitem(booya 0 random data)
  17.  
  18. This sets element 0 of array "booya" to the text string "random data".
  19. Further items may be added sequentially; the next new element in the array
  20. must be 1, and anything above 1 will result in an error.  Existing array
  21. elements may be freely overwritten:
  22.  
  23.    $setitem(booya 0 other data)
  24.  
  25. Now element 0 of array "booya" contains the string "other data".  Any item
  26. may be deleted from the array.  If the deleted element is not the last one
  27. in the array (the one with the highest item number), all items after it
  28. are shifted down by one; this prevents an array from having "holes" in it.
  29.  
  30.    $setitem(booya 1 new data)
  31.    $delitem(booya 0)
  32.  
  33. This first adds a new element, then deletes the first element.  The result
  34. is an array that is one item in size.  Item 1 become item 0.
  35.  
  36. One powerful feature of arrays not present in hashes is the ability to
  37. search through the array elements for random data.  The simplest methods are
  38. probably already familiar to you.  They operate in much the same manner as
  39. the $match() and $rmatch() functions.  Given that some array "blah" held
  40. the following items (in order, from 0):
  41.  
  42.    james@merlin.ocslink.com  nelson@nemesis.acronet.net
  43.    foobar@blah.booya.com     jbriggs@bigscreen.drivein.com
  44.  
  45. One could then use $matchitem() to find the element that best matches an
  46. arbitrary input pattern.  Similarly, if an array contained a set of wildcard
  47. patterns, $rmatchitem() could find which one best matched some non-wildcard
  48. string.
  49.  
  50. The most powerful searching feature is $finditem().  Like the matching
  51. functions, it runs through an array looking for an item that matches the
  52. input string.  However, it looks for an exact match, and is sensitive to
  53. case.  This function uses a binary search algorithm, and is quite fast.
  54.  
  55. The other feature of note is an array's ability to be sorted on the fly.
  56. All array elements have an item number (the order in which it was added) and
  57. an index number (it's sorted position in the array).  Array elements are
  58. fetched by item number with $getitem() and by index number with $igetitem().
  59. The result is that you can sequentially print out an array's elements using
  60. $igetitem(), and they will be sorted automatically.
  61.  
  62. There is more to these arrays than is presented here.  Each function used to
  63. access and manipulate them is fully documented in Section 6 of these help
  64. files.  Refer to that section for more information.
  65.  
  66.